﻿<html>
  <head>
    <title>Functions</title>
    <meta name="generator" content="h-smile:richtext"/>
  </head>
<body>
  <h1>Functions</h1>
  <p>TIScript supports named and anonymous (lambda) first class functions. Functions are objects of the Function class.</p>
  <h2><a name="named-functions" id="named-functions">Named functions</a></h2>
  <p>Named functions are declared using the following syntax:</p>
  <pre class="code tiscript">function &lt;function-name&gt; ( &lt;parameters&gt; )
{
  //...function body
}
</pre>
  <dl>
    <dt>Where:</dt>
    <dd><em>&lt;function-name&gt;</em> is a function name, either: simple&nbsp;<em>&lt;nmtoken&gt;</em> , or<br/>compound name: <em>&lt;nmtoken1&gt;</em> [ . <em>&lt;nmtoken2&gt;</em> [ . <em>&lt;nmtoken3&gt;</em> [ . <em>&lt;nmtokenN&gt;</em> ]]] <sup><a href="#fn__1" name="fnt__1" id="fnt__1" class="fn_top">1)</a></sup><br/><em>&lt;parameters&gt;</em> is a list of formal function parameters:<br/>[<em>&lt;parameter-name1&gt;</em> [ , <em>&lt;parameter-name2&gt;</em> [ , ... <em>&lt;parameter-nameN&gt;</em> ]]]</dd></dl>
  
  <h2><a name="anonymous-functions" id="anonymous-functions">Anonymous functions</a></h2>
  <p>Anonymous (a.k.a. lambda) functions can be declared in-place by using the following forms:</p>
  <p>Classic JavaScript form:</p>
  <pre>function ( &lt;parameters&gt; ) { &lt;statements&gt; }</pre>
  <h3>&quot;This&quot; lambda function declarations:</h3><p>Functions declared this way own  <i>this</i> environment variable as any other functions.</p>
	<p>Single statement lambda function form:</p>
  <pre><b>:</b> &lt;parameters&gt; <b>:</b> &lt;statement&gt;
</pre>
  <p>Block lambda function form:</p>
  <pre><b>:</b> &lt;parameters&gt; <b>{</b> &lt;statements&gt; <b>}</b> 
</pre>
  
	<h3>&quot;That&quot; lambda function declarations:</h3>
	<p>Such functions do not own  <i>this</i> environment variable. <i>this</i> environment variable gets&nbsp;resolved to <i>this</i> of outer function as in 
  <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">&quot;arrow&quot; functions in ES6</a>.</p>
	<p>Single statement lambda function form:</p>
  <pre><b>|</b> &lt;parameters&gt; <b>|</b> &lt;statement&gt;</pre>
  <p>Block lambda function form:</p>
  <pre><b>|</b> &lt;parameters&gt; <b>{</b> &lt;statements&gt; <b>}</b> 
</pre>
  
	<p>Nested functions (functions inside of other functions) are allowed.</p>
	<h2>Async functions</h2>
	<pre><b>async function </b>( &lt;parameters&gt; ) 
{ 
  (&lt;statement&gt; | &lt;await-expression&gt;)* 
}
</pre>
	<p>Async&nbsp;functions executed asynchronously and  allowed to use <b>await</b> expressions inside.</p>
	
	<h2>Generator functions</h2>
	<pre><b>function* </b>( &lt;parameters&gt; ) 
{ 
  (&lt;statement&gt; | &lt;yield-statement&gt;)* 
}
</pre>
	<p>Generator function is used in for(var x in <i>generator</i>)&nbsp; statement. Generators emit values by using&nbsp;<b>yield</b> statements.</p>
  <h2><a name="event-functions" id="event-functions">Event functions</a></h2>
  <p>Event handling function is a variant of normal function but function name given as a string. Instead of function event functions are declared with event keyword:</p>
  <pre>event name[.namespace] [$(selector)]  [( [eventObj [,element] ) ]
{
  //... event handling function body
} 
</pre><p>where:</p>
  <ul>
    <li><em>name
</em> is either one of known events or custom event name;
</li>
    <li><em>.namespace
</em> is an arbitrary event namespace name a la jQuery, optional;
</li>
    <li><em>selector
</em> &nbsp;is a CSS selector. If provided, filters only events coming from satisfying DOM elements, optional.
</li>
		<li>call parameters are optional, if provided may contain one or two parameters:<ol>
        <li>eventObj
 is a name of parameter receiving reference to instance of Event object defining details of the event. Could be any valid name like: <em>evt
</em>, <em>eo
</em> or <em>event
</em>.
</li>
        <li>element
 is a name of parameter receiving reference of DOM element.
</li>
</ol>
</li>
</ul>
  <h2><a name="optional-parameters" id="optional-parameters">Optional parameters
</a>
</h2>
  <p>TIScript supports optional parameters in function declarations:
</p>
  <h3><a name="parameters-with-default-values" id="parameters-with-default-values">Parameters with default values
</a>
</h3>
  <p>Some parameters in the function declaration may have the default value defined, for example:
</p>
  <pre class="code tiscript">function Foo(a, b, c = 12)
{
  return a + b + c;
}
</pre>
  <p>Such a function can be called with either two:
</p>
  <pre class="code tiscript">var r1 = Foo(1, 2);    // r1 = 15
</pre>
  <p>or three actual parameters:
</p>
  <pre class="code tiscript">var r2 = Foo(1, 2, 3); // r2 = 6
</pre>
  <p>The parameter with the predefined value must not have non-optional parameters to its right in the parameter list. In other words, only the last (or all) parameters can have default values.
</p>
  <h3><a name="varargs" id="varargs">Varargs
</a>
</h3>
  <p>a.k.a. Parameter vectors
</p>
  <p>There are situations when you need to define functions with the number of parameters unknown upfront. Such functions can be declared as:
</p>
  <pre class="code tiscript">function Bar(a, b, rest..)
{
  var total = a + b;
  for (var n in rest) 
    total += n;
  return total;
}
</pre>
  <p>At runtime, the variable rest
 will contain an array with actual parameters passed into the function. So, after
</p>
  <pre class="code tiscript">var r1 = Bar(1, 2, 3, 4);
</pre>
  <p>r1
 will contain value 10
, and after
</p>
  <pre class="code tiscript">var r2 = Bar(1, 2);
</pre>
  <p>r2
 will contain value 3

</p>
  <h2 id="Stringizer">Stringizer functions</h2>
  <p>Stringizer function is a normal function or method with the name starting from '$' (dollar) sign.</p>
  <p>While parsing call of such a function tiscript treats everything inside '(' and ')' as a literal string. Example:</p>
  <pre>var bodyDiv = self.$( div#body );</pre>
  <p>Such a call is a direct equivalent of the following:</p>
  <pre>var bodyDiv = self.$( &quot;div#body&quot; );</pre>
  <p>If text inside '(' and ')' &nbsp;contains unpaired bracket symbols like &nbsp;&nbsp;')' and '}' &nbsp;such symbols have to be escaped as \) &nbsp;and \}.</p>
  <h3>Stringizer parameters</h3>
  <p>The text inside '(' and ')' can contain so called tiscript code injections - sequences of tiscript code that needs to be executed and its string result to be inserted inline. To include such a code inside the string it has to be enclosed into '{' and '}' brackets. Example:</p>
  <pre>var n = 3; 
var nthDiv = self.$( div:nth-child({ n }) );</pre>
  <p>The $() call above will be translated by the parser into the following:</p>
  <pre>var nthDiv = self.$( &quot;div:nth-child(&quot;, n , &quot;)&quot; );</pre>
  <h3>Defining custom stringizer functions
</h3>
  <p>Here is real life example of the stringizer function that can be used in Sciter for inserting HTML fragments:
</p>
  <pre>function Element.$append( params.. ) // accepts html fragments with inclusions as params vector
{
  for( var i = 1; i &lt; params.length; i += 2 ) // each odd parameter is an inclusion - result of the correspondent { ... } expression.
    params[i] = params[i].toHtmlString();     // convert our inclusion into escaped HTML string for safety.
  this.insert( params.join(&quot;&quot;) );             // combine all params into single string and call Element.insert(html)
                                              // method of the DOM element in Sciter.
}
</pre>
  <p>Having such function in place we can use it now as:
</p>
  <pre>var arr = [1,2,3];
var table = self.$( table#some );
for( var n in arr )
  table.$append ( &lt;tr&gt;&lt;td&gt;Cell #{n}&lt;/td&gt;&lt;/td&gt; );
</pre>
  <p>Code above will insert three rows/cells with texts: &quot;Cell #1&quot;, &quot;Cell #2&quot; and &quot;Cell #3&quot; into the table. Pretty convenient, isn't it?
</p>
  <h2>Function call with literal object
</h2>
  <p>If some function accepts single parameter-object then it can be called omitting '(' and ')' brackets like this:
</p>
  <pre>  foo { one:1, two:2 }
</pre>
  <p>that is an exact equivalent of this standard JavaScript call:
</p>
  <pre>  foo ({ one:1, two:2 })
</pre>
  <hr/>
  <p><sup><a href="#fnt__1" id="fn__1" name="fn__1">1)
</a>
</sup> Declaration of functions with compound names is a short form for the expression:<br/>name1.name2.name3. ... .nameN = function( &lt;parameters&gt; ) { &lt;statements&gt; }

</p>
</body>
</html>